Connection: close Content-Type: text/plain Internet draft

This specification defines protocols, procedures, and conventions to be employed by peers implementing the Generic Security Service Application Program Interface (as specified in RFCs 1508 and 1509) when using Kerberos Version 5 technology (as specified in RFC 1510). ACKNOWLEDGMENTS Much of the material in this Internet-Draft is based on working documents drafted by John Wray of Digital Equipment Corporation and on discussions, implementation activities, and interoperability testing involving Marc Horowitz, Ted Ts’o, and John Wray. Particular thanks are due to each of these individuals for their contributions towards development and availability of GSS-API support within the Kerberos Version 5 code base. 1. Token Formats This section discusses protocol-visible characteristics of the GSSAPI mechanism to be implemented atop Kerberos V5 security technology Linn Document Expiration: 31 August 1996 [Page 1] Internet-Draft February 1996 per RFC-1508 and RFC-1510; it defines elements of protocol for interoperability and is independent of language bindings per RFC1509. Tokens transferred between GSS-API peers (for security context management and per-message protection purposes) are defined. The data elements exchanged between a GSS-API endpoint implementation and the Kerberos KDC are not specific to GSS-API usage and are therefore defined within RFC-1510 rather than within this specification. To support ongoing experimentation, testing, and evolution of the specification, the Kerberos V5 GSS-API mechanism as defined in this and any successor Internet-Drafts will be identified with the following Object Identifier, as defined in RFC-1510, until the specification is advanced to the level of Proposed Standard RFC: {iso(1), org(3), dod(5), internet(1), security(5), kerberosv5(2)} Upon advancement to the level of Proposed Standard RFC, the Kerberos V5 GSS-API mechanism will be identified by an Object Identifier having the value: {iso(1) member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) krb5(2)} 1.1. Context Establishment Tokens Per RFC-1508, Appendix B, the initial context establishment token will be enclosed within framing as follows: InitialContextToken ::= [APPLICATION 0] IMPLICIT SEQUENCE { thisMech MechType -MechType is OBJECT IDENTIFIER -representing "Kerberos V5" innerContextToken ANY DEFINED BY thisMech -contents mechanism-specific; -ASN.1 usage within innerContextToken -is not required } The innerContextToken of the initial context token will consist of a Kerberos V5 KRB_AP_REQ message, preceded by a two-byte token-id (TOK_ID) field, which shall contain the value 01 00. The above GSS-API framing shall be applied to all tokens emitted by the Kerberos V5 GSS-API mechanism, including KRB_AP_REP, KRB_ERROR, Linn Document Expiration: 31 August 1996 [Page 2] Internet-Draft February 1996 context-deletion, and per-message tokens, not just to the initial token in a context establishment sequence. While not required by RFC-1508, this enables implementations to perform enhanced errorchecking. The innerContextToken field of context establishment tokens for the Kerberos V5 GSS-API mechanism will contain a Kerberos message (KRB_AP_REQ, KRB_AP_REP or KRB_ERROR), preceded by a 2-byte TOK_ID field containing 01 00 for KRB_AP_REQ messages, 02 00 for KRB_AP_REP messages and 03 00 for KRB_ERROR messages. 1.1.1. Initial Token Relevant KRB_AP_REQ syntax (from RFC-1510) is as follows: AP-REQ ::= [APPLICATION 14] SEQUENCE { pvno [0] INTEGER, -indicates Version 5 msg-type [1] INTEGER, -indicates KRB_AP_REQ ap-options[2] APOptions, ticket[3] Ticket, authenticator[4] EncryptedData } APOptions ::= BIT STRING { reserved (0), use-session-key (1), mutual-required (2) } Ticket ::= [APPLICATION 1] SEQUENCE { tkt-vno [0] INTEGER, -indicates Version 5 realm [1] Realm, sname [2] PrincipalName, enc-part [3] EncryptedData } -Encrypted part of ticket EncTicketPart ::= [APPLICATION 3] SEQUENCE { flags[0] TicketFlags, key[1] EncryptionKey, crealm[2] Realm, cname[3] PrincipalName, transited[4] TransitedEncoding, authtime[5] KerberosTime, starttime[6] KerberosTime OPTIONAL, endtime[7] KerberosTime, renew-till[8] KerberosTime OPTIONAL, caddr[9] HostAddresses OPTIONAL, authorization-data[10] AuthorizationData OPTIONAL } Linn Document Expiration: 31 August 1996 [Page 3] Internet-Draft February 1996 -Unencrypted authenticator Authenticator ::= [APPLICATION 2] SEQUENCE { authenticator-vno[0] INTEGER, crealm[1] Realm, cname[2] PrincipalName, cksum[3] Checksum OPTIONAL, cusec[4] INTEGER, ctime[5] KerberosTime, subkey[6] EncryptionKey OPTIONAL, seq-number[7] INTEGER OPTIONAL, authorization-data[8] AuthorizationData OPTIONAL } For purposes of this specification, the authenticator shall include the optional sequence number, and the checksum field shall be used to convey channel binding, service flags, and optional delegation information. The checksum will have a type of 0x8003 (a value being registered within the Kerberos protocol specification), and a value field of at least 24 bytes in length. The length of the value field is extended beyond 24 bytes if and only if an optional facility to carry a Kerberos-defined KRB_CRED message for delegation purposes is supported by an implementation and active on a context. The checksum value field’s format is as follows: Byte Name Description 0..3 Lgth Number of bytes in Bnd field; Currently contains hex 10 00 00 00 (16, represented in little-endian form) 4..19 Bnd MD5 hash of channel bindings, taken over all non-null components of bindings, in order of declaration. Integer fields within channel bindings are represented in little-endian order for the purposes of the MD5 calculation. 20..23 Flags Bit vector of context-establishment flags, with values consistent with RFC-1509, p. 41: GSS_C_DELEG_FLAG: 1 GSS_C_MUTUAL_FLAG: 2 GSS_C_REPLAY_FLAG: 4 GSS_C_SEQUENCE_FLAG: 8 GSS_C_CONF_FLAG: 16 GSS_C_INTEG_FLAG: 32 The resulting bit vector is encoded into bytes 20..23 in little-endian form. 24..25 DlgOpt The Delegation Option identifier (=1) [optional] 26..27 Dlgth The length of the Deleg field. [optional] 28..n Deleg A KRB_CRED message (n = Dlgth + 29) [optional] In computing the contents of the "Bnd" field, the following detailed Linn Document Expiration: 31 August 1996 [Page 4] Internet-Draft February 1996 points apply: (1) Each integer field shall be formatted into four bytes, using little-endian byte ordering, for purposes of MD5 hash computation. (2) All input length fields within gss_buffer_desc elements of a gss_channel_bindings_struct, even those which are zero-valued, shall be included in the hash calculation; the value elements of gss_buffer_desc elements shall be dereferenced, and the resulting data shall be included within the hash computation, only for the case of gss_buffer_desc elements having non-zero length specifiers. (3) If the caller passes the value GSS_C_NO_BINDINGS instead of a valid channel bindings structure, the Bnd field shall be set to 16 zero-valued bytes. In the initial Kerberos V5 GSS-API mechanism token (KRB_AP_REQ token) from initiator to target, the GSS_C_DELEG_FLAG, GSS_C_MUTUAL_FLAG, GSS_C_REPLAY_FLAG, and GSS_C_SEQUENCE_FLAG values shall each be set as the logical AND of the initiator’s corresponding request flag to GSS_Init_sec_context() and a Boolean indicator of whether that optional service is available to GSS_Init_sec_context()’s caller. GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG, for which no corresponding context-level input indicator flags to GSS_Init_sec_context() exist, shall each be set to indicate whether their respective per-message protection services are available for use on the context being established. When input source address channel binding values are provided by a caller (i.e., unless the input argument is GSS_C_NO_BINDINGS or the source address specifier value within the input structure is GSS_C_NULL_ADDRTYPE), and the corresponding token received from the context’s peer bears address restrictions, it is recommended that an implementation of the Kerberos V5 GSS-API mechanism should check that the source address as provided by the caller matches that in the received token, and should return the GSS_S_BAD_BINDINGS major_status value if a mismatch is detected. Note: discussion is ongoing about the strength of recommendation to be made in this area, and on the circumstances under which such a recommendation should be applicable; implementors are therefore advised that changes on this matter may be included in subsequent versions of this specification. 1.1.2. Response Tokens A context establishment sequence based on the Kerberos V5 mechanism will perform one-way authentication (without confirmation or any Linn Document Expiration: 31 August 1996 [Page 5] Internet-Draft February 1996 return token from target to initiator in response to the initiator’s KRB_AP_REQ) if the mutual_req bit is not set in the application’s call to GSS_Init_sec_context(). Applications requiring confirmation that their authentication was successful should request mutual authentication, resulting in a "mutual-required" indication within KRB_AP_REQ APoptions and the setting of the mutual_req bit in the flags field of the authenticator checksum. In response to such a request, the context target will reply to the initiator with a token containing either a KRB_AP_REP or KRB_ERROR, completing the mutual context establishment exchange. Relevant KRB_AP_REP syntax is as follows: AP-REP ::= [APPLICATION 15] SEQUENCE { pvno [0] INTEGER, -represents Kerberos V5 msg-type [1] INTEGER, -represents KRB_AP_REP enc-part [2] EncryptedData } EncAPRepPart ::= [APPLICATION 27] SEQUENCE { ctime [0] KerberosTime, cusec [1] INTEGER, subkey [2] EncryptionKey OPTIONAL, seq-number [3] INTEGER OPTIONAL } The optional seq-number element within the AP-REP’s EncAPRepPart shall be included. The syntax of KRB_ERROR is as follows: KRB-ERROR ::= [APPLICATION 30] SEQUENCE { pvno[0] INTEGER, msg-type[1] INTEGER, ctime[2] KerberosTime OPTIONAL, cusec[3] INTEGER OPTIONAL, stime[4] KerberosTime, susec[5] INTEGER, error-code[6] INTEGER, crealm[7] Realm OPTIONAL, cname[8] PrincipalName OPTIONAL, realm[9] Realm, -Correct realm sname[10] PrincipalName, -Correct name e-text[11] GeneralString OPTIONAL, e-data[12] OCTET STRING OPTIONAL } Values to be transferred in the error-code field of a KRB-ERROR Linn Document Expiration: 31 August 1996 [Page 6] Internet-Draft February 1996 message are defined in [RFC-1510], not in this specification. 1.2. Per-Message and Context Deletion Tokens Three classes of tokens are defined in this section: "MIC" tokens, emitted by calls to GSS_GetMIC() (formerly GSS_Sign()) and consumed by calls to GSS_VerifyMIC() (formerly GSS_Verify()), "Wrap" tokens, emitted by calls to GSS_Wrap() (formerly GSS_Seal()) and consumed by calls to GSS_Unwrap() (formerly GSS_Unseal()), and context deletion tokens, emitted by calls to GSS_Delete_sec_context() and consumed by calls to GSS_Process_context_token(). Note: References to GSS-API per-message routines in the remainder of this specification will be based on those routines’ newer recommended names rather than those names’ predecessors. Several variants of cryptographic keys are used in generation and processing of per-message tokens: (1) context key: uses Kerberos session key (or subkey, if present in authenticator emitted by context initiator) directly (2) confidentiality key: forms variant of context key by exclusive-OR with the hexadecimal constant f0f0f0f0f0f0f0f0. (3) MD2.5 seed key: forms variant of context key by reversing the bytes of the context key (i.e. if the original key is the 8-byte sequence {aa, bb, cc, dd, ee, ff, gg, hh}, the seed key will be {hh, gg, ff, ee, dd, cc, bb, aa}). 1.2.1. Per-message Tokens MIC Use of the GSS_GetMIC() call yields a token, separate from the user data being protected, which can be used to verify the integrity of that data as received. The token has the following format: Byte no Name Description 0..1 TOK_ID Identification field. Tokens emitted by GSS_GetMIC() contain the hex value 01 01 in this field. 2..3 SGN_ALG Integrity algorithm indicator. 00 00 DES MAC MD5 01 00 MD2.5 02 00 DES MAC 4..7 Filler Contains ff ff ff ff 8..15 SND_SEQ Sequence number field. 16..23 SGN_CKSUM Checksum of "to-be-signed data", calculated according to algorithm specified in SGN_ALG field. Linn Document Expiration: 31 August 1996 [Page 7] Internet-Draft February 1996 GSS-API tokens must be encapsulated within the higher-level protocol by the application; no embedded length field is necessary. 1.2.1.1. Checksum Checksum calculation procedure (common to all algorithms): Checksums are calculated over the data field, logically prepended by the first 8 bytes of the plaintext packet header. The resulting value binds the data to the packet type and signature algorithm identifier fields. DES MAC MD5 algorithm: The checksum is formed by computing an MD5 [RFC-1321] hash over the plaintext data, and then computing a DES-CBC MAC on the 16-byte MD5 result. A standard 64-bit DES-CBC MAC is computed per [FIPS-PUB-113], employing the context key and a zero IV. The 8-byte result is stored in the SGN_CKSUM field. MD2.5 algorithm: The checksum is formed by first DES-CBC encrypting a 16-byte zero-block, using a zero IV and a key formed by reversing the bytes of the context key (i.e. if the original key is the 8-byte sequence {aa, bb, cc, dd, ee, ff, gg, hh}, the checksum key will be {hh, gg, ff, ee, dd, cc, bb, aa}). The resulting 16-byte value is logically prepended to the to-be-signed data. A standard MD5 checksum is calculated over the combined data, and the first 8 bytes of the result are stored in the SGN_CKSUM field. Note 1: we refer to this algorithm informally as "MD2.5" to connote the fact that it uses half of the 128 bits generated by MD5; use of only a subset of the MD5 bits is intended to protect against the prospect that data could be postfixed to an existing message with corresponding modifications being made to the checksum. Note 2: this algorithm is fairly novel and has received more limited evaluation than that to which other integrity algorithms have been subjected; it may not, therefore, provide the level of protection which is afforded by DES MAC MD5. DES-MAC algorithm: A standard 64-bit DES-CBC MAC is computed on the plaintext data per [FIPS-PUB-113], employing the context key and a zero IV. Padding procedures to accomodate plaintext data lengths which may not be integral multiples of 8 bytes are defined in [FIPSPUB-113]. The result is an 8-byte value, which is stored in the SGN_CKSUM field. Support for this algorithm may not be present in all implementations. 1.2.1.2. Sequence Number Sequence number field: The 8 byte plaintext sequence number field is formed from the sender’s four-byte sequence number as follows. If the four bytes of the sender’s sequence number are named s0, s1, s2 and s3 (from least to most significant), the plaintext sequence Linn Document Expiration: 31 August 1996 [Page 8] Internet-Draft February 1996 number field is the 8 byte sequence: (s0, s1, s2, s3, di, di, di, di), where ’di’ is the direction-indicator (Hex 0 sender is the context initiator, Hex FF sender is the context acceptor). The field is then DES-CBC encrypted using the context key and an IV formed from the first 8 bytes of the previously calculated SGN_CKSUM field. After sending a GSS_GetMIC() or GSS_Wrap() token, the sender’s sequence number is incremented by one. The receiver of the token will first verify the SGN_CKSUM field. If valid, the sequence number field may be decrypted and compared to the expected sequence number. The repetition of the (effectively 1-bit) direction indicator within the sequence number field provides redundancy so that the receiver may verify that the decryption succeeded. Since the checksum computation is used as an IV to the sequence number decryption, attempts to splice a checksum and sequence number from different messages will be detected. The direction indicator will detect packets that have been maliciously reflected. The sequence number provides a basis for detection of replayed tokens. Replay detection can be performed using state information retained on received sequence numbers, interpreted in conjunction with the security context on which they arrive. Provision of per-message replay and out-of-sequence detection services is optional for implementations of the Kerberos V5 GSS-API mechanism. Further, it is recommended that implementations of the Kerberos V5 GSS-API mechanism which offer these services should honor a caller’s request that the services be disabled on a context. Specifically, if replay_det_req_flag is input FALSE, replay_det_state should be returned FALSE and the GSS_DUPLICATE_TOKEN and GSS_OLD_TOKEN stati should not be indicated as a result of duplicate detection when tokens are processed; if sequence_req_flag is input FALSE, sequence_state should be returned FALSE and GSS_DUPLICATE_TOKEN, GSS_OLD_TOKEN, and GSS_UNSEQ_TOKEN stati should not be indicated as a result of out-of-sequence detection when tokens are processed. 1.2.2. Per-message Tokens Wrap Use of the GSS_Wrap() call yields a token which encapsulates the input user data (optionally encrypted) along with associated integrity check quantities. The token emitted by GSS_Wrap() consists of an integrity header whose format is identical to that emitted by GSS_GetMIC() (except that the TOK_ID field contains the value 02 01), followed by a body portion that contains either the plaintext data (if SEAL_ALG = ff ff) or encrypted data for any other supported value Linn Document Expiration: 31 August 1996 [Page 9] Internet-Draft February 1996 of SEAL_ALG. Currently, only SEAL_ALG = 00 00 is supported, and means that DES-CBC encryption is being used to protect the data. The GSS_Wrap() token has the following format: Byte no Name Description 0..1 TOK_ID Identification field. Tokens emitted by GSS_Wrap() contain the hex value 02 01 in this field. 2..3 SGN_ALG Checksum algorithm indicator. 00 00 DES MAC MD5 01 00 MD2.5 02 00 DES MAC 4..5 SEAL_ALG ff ff none 00 00 DES 6..7 Filler Contains ff ff 8..15 SND_SEQ Encrypted sequence number field. 16..23 SGN_CKSUM Checksum of plaintext padded data, calculated according to algorithm specified in SGN_ALG field. 24..last Data encrypted or plaintext padded data GSS-API tokens must be encapsulated within the higher-level protocol by the application; no embedded length field is necessary.